# Group Time Entries

## Actions
| Link                | Description                                                          | Condition                                                                                           |
|:-------------------:| -------------------------------------------------------------------- | ----------------------------------------------------------------                                    |
| updateImmediately   | Directly perform edits on this time entry                            | **Permission**: 'edit time entries' or 'edit own time entries if the time entry belongs to the user |
| delete              | Delete this time entry                                               | **Permission**: 'edit time entries' or 'edit own time entries if the time entry belongs to the user |

## Linked Properties
| Link          | Description                                                                                                                             | Type                | Constraints           | Supported operations | Condition                                 |
| :-----------: | --------------------------------------------------------------                                                                          | -------------       | --------------------- | -------------------- | ----------------------------------------- |
| self          | This time entry                                                                                                                         | TimeEntry           | not null              | READ                 |                                           |
| project       | The project the time entry is bundled in. The project might be different from the work package's project once the workPackage is moved. | Project             | not null              | READ / WRITE         |                                           |
| workPackage   | The work package the time entry is created on                                                                                           | WorkPackage         |                       | READ / WRITE         |                                           |
| user          | The user the time entry tracks expenditures for                                                                                         | User                | not null              | READ                 |                                           |
| activity      | The time entry activity the time entry is categorized as                                                                                | TimeEntriesActivity | not null              | READ / WRITE         |                                           |

Depending on custom fields defined for time entries, additional links might exist.

Time entries are either linked to a work package or to a project. If they are linked to a project, the work package reference is empty. If they are linked to a work package, the project reference is filled up automatically to point to the work package's project.

## Local Properties

| Property     | Description                                               | Type     | Constraints                                          | Supported operations | Condition                                                   |
| :----------: | --------------------------------------------------------- | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- |
| id           | Time entries' id                                          | Integer  | x > 0                                                | READ                 |                                                             |
| comment      | A text provided by the user detailing the time entry      | String   | max 255 characters                                   | READ / WRITE         |                                                             |
| spentOn      | The date the expenditure is booked for                    | Date     |                                                      | READ / WRITE         |                                                             |
| hours        | The time quantifiying the expenditure                     | Time     |                                                      | READ / WRITE         |                                                             |
| createdAt    | The time the time entry was created                       | DateTime |                                                      | READ                 |                                                             |
| updatedAt    | The time the time entry was last updated                  | DateTime |                                                      | READ                 |                                                             |

Depending on custom fields defined for time entries, additional properties might exist.

## Time entry [/api/v3/time_entries/{id}]

+ Model
    + Body

            {
                "_type": "TimeEntry",
                "id": 1,
                "comment": {
                    "format": "plain",
                    "raw": "Some text explaining why the time entry was created",
                    "html": "<p>Some text explaining why the time entry was created</p>"
                },
                "spentOn": "2015-03-20",
                "hours": "PT5H",
                "createdAt": "2015-03-20T12:56:56Z",
                "updatedAt": "2015-03-20T12:56:56Z",
                "customField12": 5,
                "_embedded": {
                    "project": {
                      ...
                    },
                    "workPackage": {
                      ...
                    },
                    "user": {
                      ...
                    },
                    "activity": {
                      ...
                    }
                },
                "_links": {
                    "self": {
                        "href": "/api/v3/time_entries/1"
                    },
                    "updateImmediately": {
                        "href": "/api/v3/time_entries/1",
                        "method": "patch"
                    },
                    "delete": {
                        "href": "/api/v3/time_entries/1",
                        "method": "delete"
                    },
                    "project": {
                        "href": "/api/v3/projects/1",
                        "title": "Some project"
                    },
                    "workPackage": {
                        "href": "/api/v3/work_packages/1",
                        "title": "Some work package"
                    },
                    "user": {
                        "href": "/api/v3/users/2",
                        "title": "Some user"
                    },
                    "activity": {
                        "href": "/api/v3/time_entries/activities/18",
                        "title": "Some time entry activity"
                    },
                    "customField4": {
                        "href": "/api/v3/users/5",
                        "title" "Some other user"
                }
            }

## View time entry [GET]

+ Parameters
    + id (required, integer, `1`) ... time entry id

+ Response 200 (application/hal+json)

    [Time entry][]

+ Response 404 (application/hal+json)

    Returned if the time entry does not exist or if the user does not have permission to view them.

    **Required permission** `view time entries` in the project the time entry is assigned to or `view own time entries` for time entries belonging to the user

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The requested resource could not be found."
            }


## Delete time entry [DELETE]

Permanently deletes the specified time entry.

+ Parameters
    + id (required, integer, `1`) ... Time entry id

+ Response 204

    Returned if the time entry was deleted successfully.

    + Body

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to access this resource."
            }

+ Response 404 (application/hal+json)

    Returned if the time entry does not exist or if the user does not have sufficient permissions to see the time entry.

    **Required permission** `view time entries` in the project the time entry is assigned to or `view own time entries` for time entries belonging to the user

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The requested resource could not be found."
            }


## Time entries [/api/v3/time_entries{?offset,pageSize,filters,sortBy}]

+ Model
    + Body

            {
              "_type": "Collection",
              "total": 39,
              "count": 2,
              "pageSize": 2,
              "offset": 1,
              "_embedded": {
                  "elements": [
                      {
                          "_type": "TimeEntry",
                          "id": 5,
                          "comment": {
                              "format": "plain",
                              "raw": "Some comment",
                              "html": "<p>Some comment</p>"
                          },
                          "spentOn": "2015-03-20",
                          "hours": "PT5H",
                          "createdAt": "2015-03-20T12:56:56Z",
                          "updatedAt": "2015-03-20T12:56:56Z",
                          "_links": {
                              "self": {
                                  "href": "/api/v3/time_entries/1"
                              },
                              "updateImmediately": {
                                  "href": "/api/v3/time_entries/1",
                                  "method": "patch"
                              },
                              "delete": {
                                  "href": "/api/v3/time_entries/1",
                                  "method": "delete"
                              },
                              "project": {
                                  "href": "/api/v3/projects/1",
                                  "title": "Some project"
                              },
                              "workPackage": {
                                  "href": "/api/v3/work_packages/1",
                                  "title": "Some work package"
                              },
                              "user": {
                                  "href": "/api/v3/users/2",
                                  "title": "Some user"
                              },
                              "activity": {
                                  "href": "/api/v3/time_entries/activities/18",
                                  "title": "Some time entry activity"
                              }
                          }
                      },
                      {
                          "_type": "TimeEntry",
                          "id": 10,
                          "comment": {
                              "format": "plain",
                              "raw": "Another comment",
                              "html": "<p>Another comment</p>"
                          },
                          "spentOn": "2015-03-21",
                          "hours": "PT7H",
                          "createdAt": "2015-03-20T12:56:56Z",
                          "updatedAt": "2015-03-20T12:56:56Z",
                          "_links": {
                              "self": {
                                  "href": "/api/v3/time_entries/2"
                              },
                              "project": {
                                  "href": "/api/v3/projects/42",
                                  "title": "Some other project"
                              },
                              "workPackage": {
                                  "href": "/api/v3/work_packages/541",
                                  "title": "Some other work package"
                              },
                              "user": {
                                  "href": "/api/v3/users/6",
                                  "title": "Some other project"
                              },
                              "activity": {
                                  "href": "/api/v3/time_entries/activities/14",
                                  "title": "some other time entry activity"
                              }
                          }
                      }
                  ]
              },
              "_links": {
                  "self": {
                      "href": "/api/v3/time_entries?offset=1&pageSize=2"
                  },
                  "jumpTo": {
                      "href": "/api/v3/time_entries?offset=%7Boffset%7D&pageSize=2",
                      "templated": true
                  },
                  "changeSize": {
                      "href": "/api/v3/time_entries?offset=1&pageSize=%7Bsize%7D",
                      "templated": true
                  },
                  "nextByOffset": {
                      "href": "/api/v3/time_entries?offset=2&pageSize=2"
                  },
                  "createTimeEntry": {
                      "href": "/api/v3/time_entries/form",
                      "method": "post"
                  },
                  "createTimeEntryImmediately": {
                      "href": "/api/v3/time_entries",
                      "method": "post"
                  }
              }
            }

## List Time entries [GET]

Lists time entries. The time entries returned depend on the filters provided and also on the permission of the requesting user.

+ Parameters
    + offset = `1` (optional, integer, `25`) ... Page number inside the requested collection.

    + pageSize (optional, integer, `25`) ... Number of elements to display per page.

    + sortBy = ["spent_on", "asc"] (optional, string, `[["spent_on", "asc"]]`) ... JSON specifying sort criteria.
    Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are:
      + id: Sort by primary key
      + hours: Sort by logged hours
      + spent_on: Sort by spent on date
      + created_on: Sort by time entry creation datetime

    + filters (optional, string, `[{ "work_package": { "operator": "=", "values": ["1", "2"] } }, { "project": { "operator": "=", "values": ["1"] } }]`) ... JSON specifying filter conditions.
    Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are:
      + work_package: Filter time entries by work package
      + project: Filter time entries by project
      + user: Filter time entries by users
      + spent_on: Filter time entries by spent on date
      + created_on: Filter time entries by creation datetime
      + activity: Filter time entries by time entry activity

+ Response 200 (application/hal+json)

    [Time entries][]

+ Response 400 (application/hal+json)

    Returned if the client sends invalid request parameters e.g. filters

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
                "message": [
                  "Filters Invalid filter does not exist."
                ]
            }

+ Response 403 (application/hal+json)

    Returned if the client is not logged in and login is required.

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to view this resource."
            }

## Create Time entry [POST]

Creates a new time entry applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a time entries' attributes and are accepted by the endpoint.

+ Request Create time entry

    + Body

            {
                "_links": {
                  "project": {
                    "href": "/api/v3/projects/34"
                  },
                  "activity": {
                    "href": "/api/v3/time_entries/activities/18"
                  },
                  "workPackage": {
                    "href": "/api/v3/work_packages/5"
                  },
                  "customField4": {
                    "href": "/api/v3/users/5"
                  },
                  "customField51": {
                    "href": "/api/v3/custom_options/11"
                  }
                },
                "hours": 'PT5H',
                "comment": {
                    "raw": "Some comment"
                },
                "spentOn": "2017-07-28",
                "customField1": {
                  "raw": "some text custom field value"
                },
                "customField8": 5
            }

+ Response 201

    [Time entry][]

+ Response 400 (application/hal+json)

    Occurs when the client did not send a valid JSON object in the request body.

    + Body

            {
                "_type": "Error",
                 "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
                "message": "The request body was not a single JSON object."
            }

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions.

    **Required permission:** Log time

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to access this resource."
            }

+ Response 422 (application/hal+json)

    Returned if:

    * a constraint for a property was violated (`PropertyConstraintViolation`)

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
                "message": "Work package is invalid.",
                "_embedded": {
                    "details": {
                        "attribute"=>"workPackage"
                    }
                }
            }

## Update Time entry [PATCH]

Updates the given time entry by applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a time entries' attributes and are accepted by the endpoint.

+ Request Update time entry

    + Body

            {
                "_links": {
                  "activity": {
                    "href": "/api/v3/time_entries/activities/18"
                  },
                  "workPackage": {
                    "href": "/api/v3/work_packages/5"
                  },
                  "customField4": {
                    "href": "/api/v3/users/5"
                  },
                  "customField51": {
                    "href": "/api/v3/custom_options/11"
                  }
                },
                "hours": "PT5H",
                "comment": {
                  "raw": "Some comment"
                },
                "spentOn": "2017-07-28",
                "customField1": {
                  "raw": "some text custom field value"
                },
                "customField8": 5
            }

+ Response 200

    [Time entry][]

+ Response 400 (application/hal+json)

    Occurs when the client did not send a valid JSON object in the request body.

    + Body

            {
                "_type": "Error",
                 "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
                "message": "The request body was not a single JSON object."
            }

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions.

    **Required permission:** Edit (own) time entries, depending on what time entry is being modified.

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to access this resource."
            }

+ Response 422 (application/hal+json)

    Returned if:

    * a constraint for a property was violated (`PropertyConstraintViolation`)

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
                "message": "Work package is invalid.",
                "_embedded": {
                    "details": {
                        "attribute"=>"workPackage"
                    }
                }
            }

## Time entry schema [/api/v3/time_entries/schema]

+ Model
    + Body

            {
                "_type": "Schema",
                "_dependencies": [],
                "id": {
                    "type": "Integer",
                    "name": "ID",
                    "required": true,
                    "hasDefault": false,
                    "writable": false,
                    "options": {}
                },
                "createdAt": {
                    "type": "DateTime",
                    "name": "Created on",
                    "required": true,
                    "hasDefault": false,
                    "writable": false,
                    "options": {}
                },
                "updatedAt": {
                    "type": "DateTime",
                    "name": "Updated on",
                    "required": true,
                    "hasDefault": false,
                    "writable": false,
                    "options": {}
                },
                "spentOn": {
                    "type": "Date",
                    "name": "Date",
                    "required": true,
                    "hasDefault": false,
                    "writable": true,
                    "options": {}
                },
                "hours": {
                    "type": "Duration",
                    "name": "Hours",
                    "required": true,
                    "hasDefault": false,
                    "writable": true,
                    "options": {}
                },
                "user": {
                    "type": "User",
                    "name": "User",
                    "required": true,
                    "hasDefault": false,
                    "writable": false,
                    "options": {}
                },
                "workPackage": {
                    "type": "WorkPackage",
                    "name": "Work package",
                    "required": false,
                    "hasDefault": false,
                    "writable": true,
                    "_links": {}
                },
                "project": {
                    "type": "Project",
                    "name": "Project",
                    "required": false,
                    "hasDefault": false,
                    "writable": true,
                    "_links": {}
                },
                "activity": {
                    "type": "TimeEntriesActivity",
                    "name": "Activity",
                    "required": true,
                    "hasDefault": true,
                    "writable": true,
                    "_links": {}
                },
                "customField29": {
                    "type": "String",
                    "name": "sfsdfsdfsdfsdfdsf",
                    "required": false,
                    "hasDefault": false,
                    "writable": true,
                    "options": {
                        "rtl": null
                    }
                },
                "_links": {
                    "self": {
                        "href": "/api/v3/time_entries/schema"
                    }
                }
            }

## View time entry schema [GET]

+ Response 200 (application/hal+json)

    [Time entry schema][]

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions to see the schema.

    **Required permission:** *log time* or *view time entries* or *edit time entries* or *edit own time entries* on any project

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to access this resource."
            }

## Time entry create form [/api/v3/time_entries/form]

This endpoint returns a form allowing a guided creation of new time entries.

For more details and all possible responses see the general specification of [Forms](/api/forms).

## Time entry create form [POST]

+ Request Create time entry form

    + Body

            {
                "_links": {
                  "activity": {
                    "href": "/api/v3/time_entries/activities/18"
                  },
                  "workPackage": {
                    "href": "/api/v3/work_packages/5"
                  }
                },
                "hours": "PT5H",
                "comment": {
                  "raw": "Some comment"
                },
                "spentOn": "2017-07-28",
                "customField1": {
                  "raw": "some text custom field value"
                },
                "customField8": 5
            }

+ Response 200 (application/hal+json)

    + Body

            {
                "_type": "Form",
                "_embedded": {
                    "payload": {
                        {
                            "_links": {
                              "project": {
                                  "href": "/api/v3/projects/1",
                                  "title": "Some project"
                              },
                              "activity": {
                                "href": "/api/v3/time_entries/activities/18",
                                "title": "Management"
                              },
                              "workPackage": {
                                "href": "/api/v3/work_packages/5",
                                "title": "non sed quis id vel quia culpa ipsam"
                              }
                            },
                            "hours": "PT5H",
                            "comment": {
                                "format": "plain",
                                "raw": "Some comment",
                                "html": "<p>Some comment</p>"
                            },
                            "spentOn": "2017-07-28",
                            "customField1": {
                              "format": "markdown",
                              "raw": "some text custom field value"
                              "html": "<p>some text custom field value</p>"
                            },
                            "customField8": 5
                        }
                    },
                    "schema": {
                        "_type": "Schema",
                        "_dependencies": [],
                        "id": {
                            "type": "Integer",
                            "name": "ID",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "createdAt": {
                            "type": "DateTime",
                            "name": "Created on",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "updatedAt": {
                            "type": "DateTime",
                            "name": "Updated on",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "spentOn": {
                            "type": "Date",
                            "name": "Date",
                            "required": true,
                            "hasDefault": false,
                            "writable": true,
                            "options": {}
                        },
                        "hours": {
                            "type": "Duration",
                            "name": "Hours",
                            "required": true,
                            "hasDefault": false,
                            "writable": true,
                            "options": {}
                        },
                        "user": {
                            "type": "User",
                            "name": "User",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "workPackage": {
                            "type": "WorkPackage",
                            "name": "Work package",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "_links": {
                                "allowedValues": {
                                    "href": "/api/v3/work_packages?filters=%5B%7B%22project%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D"
                                }
                            }
                        },
                        "project": {
                            "type": "Project",
                            "name": "Project",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "_links": {
                                "allowedValues": {
                                    "href": "/api/v3/time_entries/available_projects"
                                }
                            }
                        },
                        "activity": {
                            "type": "TimeEntriesActivity",
                            "name": "Activity",
                            "required": true,
                            "hasDefault": true,
                            "writable": true,
                            "_embedded": {
                                "allowedValues": [
                                    {
                                        "_type": "TimeEntriesActivity",
                                        "id": 18,
                                        "name": "Management",
                                        "position": 1,
                                        "default": true,
                                        "_links": {
                                            "self": {
                                                "href": "/api/v3/time_entries/activities/18",
                                                "title": "Management"
                                            },
                                            "projects": [
                                                {
                                                    "href": "/api/v3/projects/some-project",
                                                    "title": "Some project"
                                                },
                                                {
                                                    "href": "/api/v3/projects/some-other-project",
                                                    "title": "Some other project"
                                                }
                                            ]
                                        }
                                    },
                                    {
                                        "_type": "TimeEntriesActivity",
                                        "id": 23,
                                        "name": "Implementation",
                                        "position": 1,
                                        "default": true,
                                        "_links": {
                                            "self": {
                                                "href": "/api/v3/time_entries/activities/23",
                                                "title": "Implementation"
                                            },
                                            "projects": [
                                                {
                                                    "href": "/api/v3/projects/some-project",
                                                    "title": "Some project"
                                                }
                                            ]
                                        }
                                    }
                                ]
                            },
                            "_links": {
                                "allowedValues": [
                                    {
                                        "href": "/api/v3/time_entries/activities/18",
                                        "title": "Management"
                                    },
                                    {
                                        "href": "/api/v3/time_entries/activities/23",
                                        "title": "Implementation"
                                    }
                                ]
                            }
                        },
                        "customField1": {
                            "type": "Formattable",
                            "name": "Some formattable",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "options": {
                                "rtl": null
                            }
                        },
                        "customField8": {
                            "type": "Integer",
                            "name": "Some integer",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "options": {
                                "rtl": null
                            }
                        },
                        "_links": {}
                    },
                    "validationErrors": {}
                },
                "_links": {
                    "self": {
                        "href": "/api/v3/time_entries/form",
                        "method": "post"
                    },
                    "validate": {
                        "href": "/api/v3/time_entries/form",
                        "method": "post"
                    },
                    "commit": {
                        "href": "/api/v3/time_entries",
                        "method": "post"
                    }
                }
            }

+ Response 400 (application/hal+json)

    Occurs when the client did not send a valid JSON object in the request body.

    + Body

            {
                "_type": "Error",
                 "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
                "message": "The request body was not a single JSON object."
            }

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions.

    **Required permission:** *log time* in any project

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to access this resource."
            }

## Time entry update form [/api/v3/time_entries/:id/form]

This endpoint returns a form allowing a guided update of existing time entries.

For more details and all possible responses see the general specification of [Forms](/api/forms).

## Time entry update form [POST]

+ Request Create time entry form

    + Body

            {
                "_links": {
                  "workPackage": {
                    "href": "/api/v3/work_packages/9"
                  }
                },
                "hours": "PT8H",
                "customField1": {
                  "raw": "some altered text custom field value"
            }

+ Response 200 (application/hal+json)

    + Body

            {
                "_type": "Form",
                "_embedded": {
                    "payload": {
                        {
                            "_links": {
                              "project": {
                                  "href": "/api/v3/projects/1",
                                  "title": "Some project"
                              },
                              "activity": {
                                "href": "/api/v3/time_entries/activities/18",
                                "title": "Management"
                              },
                              "workPackage": {
                                "href": "/api/v3/work_packages/9",
                                "title": "The updated work package"
                              }
                            },
                            "hours": "PT8H",
                            "comment": {
                                "format": "plain",
                                "raw": "Some comment",
                                "html": "<p>Some comment</p>"
                            },
                            "spentOn": "2017-07-28",
                            "customField1": {
                              "format": "markdown",
                              "raw": "some altered text custom field value"
                              "html": "<p>some altered text custom field value</p>"
                            },
                            "customField8": 5
                        }
                    },
                    "schema": {
                        "_type": "Schema",
                        "_dependencies": [],
                        "id": {
                            "type": "Integer",
                            "name": "ID",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "createdAt": {
                            "type": "DateTime",
                            "name": "Created on",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "updatedAt": {
                            "type": "DateTime",
                            "name": "Updated on",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "spentOn": {
                            "type": "Date",
                            "name": "Date",
                            "required": true,
                            "hasDefault": false,
                            "writable": true,
                            "options": {}
                        },
                        "hours": {
                            "type": "Duration",
                            "name": "Hours",
                            "required": true,
                            "hasDefault": false,
                            "writable": true,
                            "options": {}
                        },
                        "user": {
                            "type": "User",
                            "name": "User",
                            "required": true,
                            "hasDefault": false,
                            "writable": false,
                            "options": {}
                        },
                        "workPackage": {
                            "type": "WorkPackage",
                            "name": "Work package",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "_links": {
                                "allowedValues": {
                                    "href": "/api/v3/work_packages?filters=%5B%7B%22project%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D"
                                }
                            }
                        },
                        "project": {
                            "type": "Project",
                            "name": "Project",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "_links": {
                                "allowedValues": {
                                    "href": "/api/v3/time_entries/available_projects"
                                }
                            }
                        },
                        "activity": {
                            "type": "TimeEntriesActivity",
                            "name": "Activity",
                            "required": true,
                            "hasDefault": true,
                            "writable": true,
                            "_embedded": {
                                "allowedValues": [
                                    {
                                        "_type": "TimeEntriesActivity",
                                        "id": 18,
                                        "name": "Management",
                                        "position": 1,
                                        "default": true,
                                        "_links": {
                                            "self": {
                                                "href": "/api/v3/time_entries/activities/18",
                                                "title": "Management"
                                            },
                                            "projects": [
                                                {
                                                    "href": "/api/v3/projects/some-project",
                                                    "title": "Some project"
                                                },
                                                {
                                                    "href": "/api/v3/projects/some-other-project",
                                                    "title": "Some other project"
                                                }
                                            ]
                                        }
                                    },
                                    {
                                        "_type": "TimeEntriesActivity",
                                        "id": 23,
                                        "name": "Implementation",
                                        "position": 1,
                                        "default": true,
                                        "_links": {
                                            "self": {
                                                "href": "/api/v3/time_entries/activities/23",
                                                "title": "Implementation"
                                            },
                                            "projects": [
                                                {
                                                    "href": "/api/v3/projects/some-project",
                                                    "title": "Some project"
                                                }
                                            ]
                                        }
                                    }
                                ]
                            },
                            "_links": {
                                "allowedValues": [
                                    {
                                        "href": "/api/v3/time_entries/activities/18",
                                        "title": "Management"
                                    },
                                    {
                                        "href": "/api/v3/time_entries/activities/23",
                                        "title": "Implementation"
                                    }
                                ]
                            }
                        },
                        "customField1": {
                            "type": "Formattable",
                            "name": "Some formattable",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "options": {
                                "rtl": null
                            }
                        },
                        "customField8": {
                            "type": "Integer",
                            "name": "Some integer",
                            "required": false,
                            "hasDefault": false,
                            "writable": true,
                            "options": {
                                "rtl": null
                            }
                        },
                        "_links": {}
                    },
                    "validationErrors": {}
                },
                "_links": {
                    "self": {
                        "href": "/api/v3/time_entries/42/form",
                        "method": "post"
                    },
                    "validate": {
                        "href": "/api/v3/time_entries/42/form",
                        "method": "post"
                    },
                    "commit": {
                        "href": "/api/v3/time_entries/42",
                        "method": "post"
                    }
                }
            }

+ Response 400 (application/hal+json)

    Occurs when the client did not send a valid JSON object in the request body.

    + Body

            {
                "_type": "Error",
                 "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
                "message": "The request body was not a single JSON object."
            }

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions to edit the time entry.

    **Required permission:** *edit time entries* for every time entry of a project, or *edit own time entries* for time entries belonging to the user.

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to access this resource."
            }

+ Response 404 (application/hal+json)

    Returned if the time entry does not exist or if the client does not have sufficient permissions to view it.

    **Required permission** `view time entries` in the project the time entry is assigned to or `view own time entries` for time entries belonging to the user

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The requested resource could not be found."
            }

## Available projects for time entries [/api/v3/time_entries/available_projects]

+ Model
    + Body

            {
              "_links": {
                "self": {
                  "href": "/api/v3/time_entries/available_projects"
                }
              },
              "_type": "Collection",
              "total": 2,
              "count": 2,
              "_embedded": {
                "elements": [
                  {
                    "_type": "Project",
                    << omitted for brevity >>
                  },
                  {
                    "_type": "Project",
                    << omitted for brevity >>
                  }
                ]
              }
            }

## Available projects for time entries [GET]

Gets a list of projects in which a time entry can be created in or be assigned to on update. The list contains all projects in which the user issuing the request has the necessary permissions.

+ Response 200 (application/hal+json)

    [Available projects for time entries][]

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions.

    **Required permission:** *log time*, *edit time entries* or *edit own time entries* in any project

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to access this resource."
            }


# Group Time Entry Activities

Time entries are classified by an activity which is one item of a set of user defined activities (e.g. Design, Specification, Development).

## Actions

None

## Linked Properties
| Link          | Description                                                    | Type                | Constraints           | Supported operations | Condition                                 |
| :-----------: | -------------------------------------------------------------- | -------------       | --------------------- | -------------------- | ----------------------------------------- |
| self          | This time entry activity                                       | TimeEntriesActivity | not null              | READ                 |                                           |
| projects      | List of projects the time entry is active in                   | []Project           | not null              | READ / WRITE         |                                           |

## Local Properties

| Property     | Description                                                  | Type     | Constraints                                          | Supported operations | Condition                                                   |
| :----------: | ---------------------------------------------------------    | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- |
| id           | Time entries' id                                             | Integer  | x > 0                                                | READ                 |                                                             |
| name         | The human readable name chosen for this activity             | String   | max 30 characters                                    | READ                 |                                                             |
| position     | The rank the activity has in a list of activities            | Date     |                                                      | READ                 |                                                             |
| default      | Flag to signal whether this activity is the default activity | Boolean  |                                                      | READ                 |                                                             |


## Time entries activity [/api/v3/time_entries/activity/{id}]

+ Model
    + Body

            {
                "_type": "TimeEntriesActivity",
                "id": 18,
                "name": "a autem",
                "position": 10,
                "default": false,
                "_embedded": {
                    "projects": [
                      ...
                    ]
                },
                "_links": {
                    "self": {
                        "href": "/api/v3/time_entries/activities/18",
                        "title": "a autem"
                    },
                    "projects": [
                        {
                            "href": "/api/v3/projects/seeded_project",
                            "title": "Seeded Project"
                        },
                        {
                            "href": "/api/v3/projects/working-project",
                            "title": "Working Project"
                        }
                    ]
                }
            }

## View time entries activity[GET]

+ Parameters
    + id (required, integer, `1`) ... time entries activity id

+ Response 200 (application/hal+json)

    [Time entries activity][]

+ Response 404 (application/hal+json)

    Returned if the activity does not exist or if the user does not have permission to view them.

    **Required permission** `view time entries`, `log time`, `edit time entries`, `edit own time entries` or `manage project activities` in any project

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The requested resource could not be found."
            }
